v1.8.0

Compare Source

Minor Changes

• Added MCP tool annotations to the requireToolApproval context and exposed them on tools returned from listTools() / listToolsets(). (#​16784)

  The requireToolApproval callback now receives the server-advertised annotations (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint) alongside toolName and args. This lets you write declarative approval policies instead of hardcoding tool name lists. Annotations are also propagated onto Mastra tools as tool.mcp.annotations so apps can render them in UI.

  Security caveat (per the MCP spec): annotations are hints, not guarantees. Clients MUST treat them as untrusted unless they come from a trusted server. Do not use annotations alone as a security boundary for servers you do not control — set requireToolApproval: true for those. When the server omits annotations entirely, this field is undefined, so policies can distinguish "no annotations" from "annotated as safe".

  import { MCPClient } from '@​mastra/mcp';
  
  // Before — hardcoded tool name lists, server-specific
  const mcp = new MCPClient({
    servers: {
      github: {
        url: new URL('https://example.com/mcp'),
        requireToolApproval: ({ toolName }) => toolName === 'delete_repo',
      },
    },
  });
  
  // After — annotation-driven, works across any trusted MCP server
  const mcp = new MCPClient({
    servers: {
      github: {
        url: new URL('https://example.com/mcp'),
        requireToolApproval: ({ annotations }) => {
          if (!annotations) return true;
          if (annotations.readOnlyHint) return false;
          if (annotations.destructiveHint) return true;
          return false;
        },
      },
    },
  });
  
  // Annotations are also visible on tools returned by listTools()
  const tools = await mcp.listTools();
  for (const tool of Object.values(tools)) {
    console.log(tool.mcp?.annotations);
  }

  Closes #​16766.

Patch Changes

• Fixed an issue where OAuth token requests dropped client_id and client_secret for confidential clients. The provider previously shipped an empty addClientAuthentication method that satisfied the MCP SDK's existence check and short-circuited its default credential attachment, causing invalid_request errors on token exchange and refresh against confidential-client OAuth servers. The empty stub has been removed so the SDK's built-in client authentication runs again. See #​16854. (#​16862)

• Close previous SSE transport before accepting a new connection in MCPServer.connectSSE(). Previously, sequential SSE connections to the same server would fail with "Already connected to a transport" because the underlying protocol was never closed when the previous client disconnected. (#​16695)

• Updated dependencies [452036a, c272d50, 27fd1b7, 5ba7253, 5556cc1, f73980d, 5499303, a702009, 9aee493, d8692af, 1a9cc60, 8cdb86c, 8534d79, eda90c5, a935b0a, 9c88701, c78f8cd, e146aad, ac79462, 1a0ec78, e47bca7, afc004f, 0031d0f, 841a222, 64c1e0b, 40d83a9, 4e88dc6, 19018f0, 19281c7, 3498b49, d52b6fe, 408be73, 359439b, 71a820b, 1698f5e]:

  • @​mastra/core@​1.36.0

v1.7.0

Compare Source

Minor Changes

• Added MCP Apps support for interactive UI rendering over MCP. (#​16004)

  MCPClientServerProxy — a lightweight proxy that delegates resource and tool operations to remote MCP servers via MCPClient, enabling Studio to fetch app resources from any connected server.

  toMCPServerProxies() — new convenience method on MCPClient that creates proxy objects for all configured servers, ready for Mastra-level registration.

  Automatic serverId stamping — tools returned by listTools() now carry _meta.ui.serverId, allowing consumers to resolve ui:// app resources from the correct MCP server in multi-server environments.

  const mcp = new MCPClient({
    servers: {
      myApps: { url: new URL('https://my-mcp-server.example.com/mcp') },
    },
  });
  
  const mastra = new Mastra({
    agents: { myAgent },
    mcpServers: { ...mcp.toMCPServerProxies() },
  });

• Added MCP Apps extension support (SEP-1865). MCPServer now accepts an appResources config to register interactive ui:// HTML resources. MCPClient preserves full tool _meta (including ui.resourceUri) when converting MCP tools to Mastra tools. Both advertise the io.modelcontextprotocol/ui extension capability. (#​16004)

  Example — MCPServer with app resources:

  const server = new MCPServer({
    name: 'my-server',
    tools: { myTool },
    appResources: {
      dashboard: {
        name: 'Dashboard',
        description: 'Interactive dashboard UI',
        html: '<html>...</html>',
      },
    },
  });

Patch Changes

• Added Fine-Grained Authorization (FGA) enforcement to MCP tool execution. Both transport-driven calls and direct executeTool() calls now run the same authorization checks when a request user is present, and typed FGA permission constants are accepted in MCP server authorization config. (#​15410)

• Fixed trace parenting for long-lived MCP Stream connections. (#​15716)

• Updated dependencies [6dcd65f, 86c0298, c05c9a1, ca28c23, e24aacb, 7679a63, 7fce309, 1d64a76, 1c2dda8, c721164, 1b55954, 7997c2e, 5adc55e, 7679a63, a0d9b6d, e97ccb9, c5daf48, 70017d7, cd96779, b0c7022, e4942bc]:

  • @​mastra/core@​1.32.0

v1.6.0

Compare Source

Minor Changes

• Added jsonSchemaValidator pass-through option on MCPClient server entries and MCPServer. Forward this option from @modelcontextprotocol/sdk to opt into a non-default validator. Pass CfWorkerJsonSchemaValidator from @modelcontextprotocol/sdk/validation/cfworker to make tools with outputSchema work in Cloudflare Workers / V8 isolates, where the default Ajv validator's new Function(...) compile path is blocked. (#​15866)

  import { MCPClient, MCPServer } from '@​mastra/mcp';
  import { CfWorkerJsonSchemaValidator } from '@​modelcontextprotocol/sdk/validation/cfworker';
  
  const mcp = new MCPClient({
    servers: {
      upstream: {
        url: new URL('https://example/mcp'),
        jsonSchemaValidator: new CfWorkerJsonSchemaValidator(),
      },
    },
  });
  
  const server = new MCPServer({
    name: 'My Server',
    version: '1.0.0',
    tools: { ... },
    jsonSchemaValidator: new CfWorkerJsonSchemaValidator(),
  });

  Closes #​15862.

Patch Changes

• Updated dependencies [28caa5b, c1ae974, b510d36, 13b4d7c, 7a7b313, c04417b, cf25a03, 8a71261, 9e973b0, dd934a0, ba6b0c5, a6dac0a, 5a4b1ee, 5a4b1ee, 5a4b1ee, 6c8c6c7, 5a4b1ee, 7d056b6, 9cef83b, d30e215, 021a60f, 73f2809, aedeea4, 26f1f94, 8126d86, 73b45fa, ae97520, 7a7b313, 441670a]:
  • @​mastra/core@​1.29.0

v1.5.2

Compare Source

Patch Changes

• Replace uuid with @lukeed/uuid and node:crypto (#​15691)

• Updated dependencies [733bf53, 5405b3b, 45e29cb, 750b4d3, c321127, a07bcef, 696694e, b084a80, 82b7a96, df97812, 8bbe360, f6b8ba8, a07bcef]:

  • @​mastra/core@​1.28.0

v1.5.1

Compare Source

Patch Changes

• Fixed MCP tool strict mode propagation. MCP servers now expose Mastra tool strictness in MCP metadata, and the MCP client restores that flag when rebuilding tools so strict OpenAI tool calling works for MCP-backed tools too. (#​15397)

• Fixed MCP tools with recursive JSON Schema refs so they stay serializable when loaded. (#​15400)

• Updated dependencies [20f59b8, aba393e, 3d83d06, e2687a7, fdd54cf, 6315317, a371ac5, 0474c2b, 0a5fa1d, 7e0e63e, ea43e64, f607106, 30456b6, 9d11a8c, 9d3b24b, 00d1b16, 47cee3e, 62919a6, d246696, 354f9ce, 16e34ca, 7020c06, 8786a61, 9467ea8, 7338d94, c80dc16, af8a57e, d63ffdb, 47cee3e, 1bd5104, e9837b5, 8f1b280, 92dcf02, 0fd90a2, 8fb2405, 12df98c]:

  • @​mastra/core@​1.26.0

v1.5.0

Compare Source

Minor Changes

• Added requireToolApproval option to MCP server configuration for requiring human approval before tool execution. Supports both boolean (all tools) and function (dynamic per-tool logic). (#​15315)

Patch Changes

• Preserve forwarded MCP client elicitation capabilities so client-supported URL and form elicitations work correctly. (#​15233)

• Updated dependencies [87df955, 8fad147, 582644c, cbdf3e1, 8fe46d3, 18c67db, 4ba3bb1, 5d84914, 8dcc77e, aa67fc5, fd2f314, fa8140b, 190f452, e80fead, 0287b64, 7e7bf60, 184907d, 075e91a, 0c4cd13, b16a753]:

  • @​mastra/core@​1.25.0

v1.4.2

Compare Source

Patch Changes

• Improved MCP tool discovery to retry once after reconnectable connection errors like Connection closed during tools/list. (#​15141)

  MCPClient.listToolsets(), listToolsetsWithErrors(), and listTools() now attempt a reconnect before treating transient discovery failures as missing tools.

• Fixed MCP server to return HTTP 404 (instead of 400) when a client sends a stale or unknown session ID. Per the MCP spec, this tells clients to re-initialize with a new session, which fixes broken tool calls after server redeploys. (#​15160)

• Updated dependencies [8db7663, 153e864, 715710d, 378c6c4, 9f91fd5, ba6fa9c]:

  • @​mastra/core@​1.24.0

v1.4.1

Compare Source

Patch Changes

• Standardized all logger calls across the codebase to use static string messages with structured data objects. Dynamic values are now passed as key-value pairs in the second argument instead of being interpolated into template literal strings. This improves log filterability and searchability in observability storage. (#​14899)

  Removed ~150 redundant or noisy log calls including duplicate error logging after trackException and verbose in-memory storage CRUD traces.

• Updated dependencies [cbeec24, cee146b, aa0aeff, 2bcec65, ad9bded, cbeec24, 208c0bb, f566ee7]:

  • @​mastra/core@​1.20.0

v1.4.0

Compare Source

Minor Changes

• Added support for passing custom _meta metadata when calling tools on external MCP servers. The execute context now accepts an optional _meta field with arbitrary key-value pairs that are forwarded in the callTool request, enabling use cases like distributed tracing, compliance tagging, and multi-tenant routing. Custom _meta is merged with the progress token when progress tracking is enabled. (#​14809)

  const tools = await mcpClient.tools();
  await tools['my_tool'].execute({ query: 'active users' }, { _meta: { traceId: 'span-456', tenantId: 'org-123' } });

  When enableProgressTracking is enabled, the progressToken is automatically merged into _meta alongside your custom fields.

Patch Changes

• Updated dependencies [180aaaf, 9140989, d7c98cf, acf5fbc, 24ca2ae, 0762516, 9c57f2f, 5bfc691, 2de3d36, d3736cb, c627366]:
  • @​mastra/core@​1.19.0

v1.3.2

Compare Source

Patch Changes

• Fixed MCP server returning confusing output schema errors when tool input fails Zod validation but passes JSON Schema validation. The server now correctly returns isError: true with the validation error message. (#​14853)

• Updated dependencies [dc514a8, e333b77, dc9fc19, 60a224d, fbf22a7, f16d92c, 949b7bf, 404fea1, ebf5047, 12c647c, d084b66, 79c699a, 62757b6, 675f15b, b174c63, 819f03c, 04160ee, 2c27503, 424a1df, 3d70b0b, eef7cb2, 260fe12, 12c88a6, 43595bf, 78670e9, e8a5b0b, 3b45a13, d400e7c, f58d1a7, a49a929, 8127d96]:

  • @​mastra/core@​1.18.0

v1.3.1

Compare Source

Patch Changes

• Fixed MCP tool results to preserve the standard CallToolResult envelope shape. Previously, content was extracted from the envelope which broke consumers expecting the standard MCP result format. Output schema validation is now handled internally by the MCP SDK's AJV validator instead of Zod, preventing unrecognized keys from being stripped. (#​14519)

• Fix MCP tool results returning empty {} when tool has no outputSchema (#​14372)

• Fixed child processes started by the MCP client staying alive after the terminal session closes. (#​13977)

• Fixed regular tools executed via MCPServer now receive requestContext populated from mcp.extra, matching the behavior of agent and workflow tools. All tool types now consistently propagate authentication and request context. (#​14349)

• Updated dependencies [cb611a1, da93115, 62d1d3c, 9e1a3ed, 8681ecb, 28d0249, 681ee1c, bb0f09d, a579f7a, 5f7e9d0, d7f14c3, 0efe12a]:

  • @​mastra/core@​1.15.0

v1.3.0

Compare Source

Minor Changes

• Added new MCP client APIs for per-server control and diagnostics. (#​14377)

  • Added reconnectServer(serverName) to reconnect a single MCP server without restarting all servers.
  • Added listToolsetsWithErrors() to return both toolsets and per-server errors.
  • Added getServerStderr(serverName) to inspect piped stderr for stdio servers.

  Example

  const { toolsets, errors } = await mcpClient.listToolsetsWithErrors();
  await mcpClient.reconnectServer('slack');
  const stderr = mcpClient.getServerStderr('slack');

Patch Changes

• Improved (#​14260)

  • Updated @modelcontextprotocol/sdk from ^1.17.5 to ^1.27.1.

  Deprecated

  • Deprecated prompt version usage in @mastra/mcp.
  • Prompt versions are not part of MCP protocol behavior and will be removed.

  Migration

  • Use unique prompt names instead of prompt versions.
  • Before: client.prompts.get({ name: 'explain-code', version: 'v1', args })
  • After: client.prompts.get({ name: 'explain-code-v1', args })
  • MastraPrompt is available for migration and is also deprecated.

• Updated dependencies [51970b3, 4444280, 085e371, b77aa19, dbb879a, 8b4ce84, 8d4cfe6, dd6ca1c, ce26fe2, 68a019d, 4cb4edf, 8de3555, b26307f, 68a019d]:

  • @​mastra/core@​1.14.0

v1.2.1

Compare Source

Patch Changes

• Fixed TypeScript compilation errors when using MCP resource methods in projects with pnpm workspaces. (#​14229)

• Updated dependencies [ea86967, db21c21, 11f5dbe, 6751354, c958cd3, 86f2426, 950eb07]:

  • @​mastra/core@​1.13.0

v1.2.0

Compare Source

Minor Changes

• MCP client now attaches mcpMetadata (server name and version) to every tool it creates, enabling automatic MCP_TOOL_CALL span tracing without user code changes. (#​13274)

Patch Changes

• Added stderr and cwd options to stdio server configuration so you can control child process error output and set the server working directory. (#​13959)

  import { MCPClient } from '@​mastra/mcp';
  
  const mcp = new MCPClient({
    servers: {
      myServer: {
        command: 'node',
        args: ['server.js'],
        stderr: 'pipe',
        cwd: '/path/to/server',
      },
    },
  });

• Updated dependencies [cddf895, 9cede11, a59f126, ed8fd75, c510833, c4c7dad, 45c3112, 7296fcc, 00c27f9, 5e7c287, 7e17d3f, ee19c9b]:

  • @​mastra/core@​1.12.0

v1.1.0

Compare Source

Minor Changes

• Added requestContext support to the custom fetch option in MCP client HTTP server definitions. The fetch function now receives the current request context as an optional third argument, enabling users to forward authentication cookies, bearer tokens, and other request-scoped data from the incoming request to remote MCP servers during tool execution. (#​13773)

  Example usage:

  const mcp = new MCPClient({
    servers: {
      myServer: {
        url: new URL('https://api.example.com/mcp'),
        fetch: async (url, init, requestContext) => {
          const headers = new Headers(init?.headers);
          const cookie = requestContext?.get('cookie');
          if (cookie) {
            headers.set('cookie', cookie);
          }
          return fetch(url, { ...init, headers });
        },
      },
    },
  });

  This change is fully backward-compatible — existing fetch functions with (url, init) signatures continue to work unchanged. Closes #​13769.

Patch Changes

• Updated dependencies [41e48c1, 82469d3, 33e2fd5, 7ef6e2c, b12d2a5, fa37d39, b12d2a5, 71c38bf, f993c38, f51849a, 9bf3a0d, cafa045, 1fd9ddb, 6135ef4, d9d228c, 5576507, 79d69c9, 94f44b8, 13187db, 2ae5311, 6135ef4]:
  • @​mastra/core@​1.10.0

v1.0.3

Compare Source

Patch Changes

• Isolate per-server failures in listTools() and listToolsets() so one failing MCP server no longer collapses tool loading for all healthy servers. (#​13527)

  What changed:

  • listTools() and listToolsets() now use per-server try/catch with error logging instead of Promise.all, matching the existing pattern in resources.list() and prompts.list()
  • disconnect() uses Promise.allSettled so one failing disconnect does not block others
  • Removed unused eachClientTools() private method

• Fixed MCP tool results being silently stripped to empty objects ({}) when the server's output schema doesn't exactly match the returned data. Zod's default behavior removes unknown keys during validation, which caused tools (especially FastMCP servers) to return {} instead of the full result. Output schemas now preserve all fields returned by the MCP server. (#​13588)

• Fixed MCP tool calls to retry automatically after a stream disconnect, instead of failing on the first attempt. (#​13686)

• Updated dependencies [504fc8b, f9c150b, 88de7e8, edee4b3, 3790c75, e7a235b, d51d298, 6dbeeb9, d5f0d8d, 09c3b18, b896379, 85c84eb, a89272a, ee9c8df, 77b4a25, 276246e, 08ecfdb, d5f628c, 524c0f3, c18a0e9, 4bd21ea, 115a7a4, 22a48ae, 3c6ef79, 9311c17, 7edf78f, 1c4221c, d25b9ea, fe1ce5c, b03c0e0, 0a8366b, 85664e9, bc79650, 9257d01, 3a3a59e, 3108d4e, 0c33b2c, 191e5bd, f77cd94, e8135c7, daca48f, 257d14f, 352f25d, 93477d0, 31c78b3, 0bc0720, 36516ac, e947652, 3c6ef79, 9257d01, ec248f6]:

  • @​mastra/core@​1.9.0

v1.0.2

Compare Source

Patch Changes

• Fixed MCP tool results returning empty {} when the server does not include structuredContent in responses (e.g. FastMCP, older MCP protocol versions). The client now extracts the actual result from

✂ Note

PR body was truncated to here.